Skip to content

fix: crowdin MDX heading anchor handling#488

Merged
elibosley merged 1 commit into
mainfrom
fix/crowdin-mdx-release-note-anchors-main
May 24, 2026
Merged

fix: crowdin MDX heading anchor handling#488
elibosley merged 1 commit into
mainfrom
fix/crowdin-mdx-release-note-anchors-main

Conversation

@elibosley
Copy link
Copy Markdown
Member

@elibosley elibosley commented May 24, 2026

Summary

Fix the Crowdin release-note generation path so .md release-note sources are parsed as MDX and translated explicit heading anchors stay in MDX-safe comment form.

  • configure Crowdin .md and .mdx docs mappings to use mdx_v2_4
  • keep release-note paths as .md so existing raw links do not break
  • add source-side MDX-safe heading anchors where translations already depended on stable anchors
  • normalize translated release-note heading anchors away from escaped comments, classic {#anchor} ids, and HTML-comment anchors
  • keep Crowdin scripts pinned to --branch main

Root Cause

The release-note .md files were stored in Crowdin as plain Markdown sources. Crowdin then escaped or malformed MDX heading anchor comments on export. Recreating the release-note source records as MDX parser records fixed the generation path without renaming files to .mdx.

Validation

  • pnpm exec crowdin config lint --config crowdin.yml
  • git diff --check origin/main...HEAD -- crowdin.yml package.json docs/unraid-os/release-notes i18n
  • local release-note anchor scans: 0 escaped MDX comments, 0 classic heading IDs, 0 HTML-comment heading anchors
  • Crowdin release-note source records verified as mdx_v2 parser version 4
  • Crowdin 220 file/language release-note round-trip export completed with 0 failures before this branch was cut
  • post-upload Crowdin smoke exports for de/6.12.4, de/7.0.0, fr/7.2.0, and zh-CN/7.2.0 returned clean anchors

Full build intentionally not run per repo guidance.

Summary by CodeRabbit

  • Documentation

    • Updated documentation formatting and anchor syntax across all localized release notes (German, Spanish, French, and Chinese) for improved consistency.
    • Refined Crowdin localization configuration for more precise file mapping and content handling.
  • Chores

    • Enhanced localization build scripts with explicit branch targeting for improved deployment control.

Review Change Stack

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented May 24, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 5aa11412-34f7-4323-93dd-28c21d99bcc3

📥 Commits

Reviewing files that changed from the base of the PR and between b5c1bc6 and 30a1983.

📒 Files selected for processing (152)
  • crowdin.yml
  • docs/unraid-os/release-notes/6.12.0.md
  • docs/unraid-os/release-notes/6.12.1.md
  • docs/unraid-os/release-notes/6.12.10.md
  • docs/unraid-os/release-notes/6.12.11.md
  • docs/unraid-os/release-notes/6.12.12.md
  • docs/unraid-os/release-notes/6.12.13.md
  • docs/unraid-os/release-notes/6.12.14.md
  • docs/unraid-os/release-notes/6.12.15.md
  • docs/unraid-os/release-notes/6.12.2.md
  • docs/unraid-os/release-notes/6.12.3.md
  • docs/unraid-os/release-notes/6.12.4.md
  • docs/unraid-os/release-notes/6.12.5.md
  • docs/unraid-os/release-notes/6.12.6.md
  • docs/unraid-os/release-notes/6.12.8.md
  • docs/unraid-os/release-notes/6.12.9.md
  • docs/unraid-os/release-notes/7.0.0.md
  • docs/unraid-os/release-notes/7.0.1.md
  • docs/unraid-os/release-notes/7.1.0.md
  • docs/unraid-os/release-notes/7.1.1.md
  • docs/unraid-os/release-notes/7.1.2.md
  • docs/unraid-os/release-notes/7.1.3.md
  • docs/unraid-os/release-notes/7.1.4.md
  • docs/unraid-os/release-notes/7.2.0.md
  • docs/unraid-os/release-notes/7.2.1.md
  • docs/unraid-os/release-notes/7.2.2.md
  • docs/unraid-os/release-notes/7.2.3.md
  • docs/unraid-os/release-notes/7.2.4.md
  • docs/unraid-os/release-notes/7.2.5.md
  • docs/unraid-os/release-notes/7.2.6.md
  • docs/unraid-os/release-notes/7.3.0.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.0.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.1.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.10.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.11.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.12.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.13.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.14.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.15.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.2.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.3.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.4.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.5.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.6.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.8.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.9.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.0.0.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.0.1.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.0.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.1.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.2.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.3.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.4.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.0.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.1.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.2.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.3.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.4.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.5.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.6.md
  • i18n/de/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.3.0.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.0.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.1.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.10.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.11.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.12.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.13.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.14.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.15.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.2.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.3.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.4.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.5.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.6.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.8.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.9.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.0.0.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.0.1.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.0.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.1.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.2.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.3.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.4.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.0.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.1.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.2.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.3.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.4.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.5.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.6.md
  • i18n/es/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.3.0.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.0.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.1.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.10.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.11.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.12.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.13.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.14.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.15.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.2.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.3.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.4.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.5.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.6.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.8.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.9.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.0.0.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.0.1.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.0.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.1.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.2.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.3.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.4.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.0.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.1.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.2.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.3.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.4.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.5.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.6.md
  • i18n/fr/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.3.0.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.0.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.1.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.10.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.11.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.12.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.13.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.14.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.15.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.2.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.3.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.4.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.5.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.6.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.8.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/6.12.9.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.0.0.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.0.1.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.0.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.1.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.2.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.3.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.1.4.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.0.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.1.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.2.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.3.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.4.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.5.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.2.6.md
  • i18n/zh/docusaurus-plugin-content-docs/current/unraid-os/release-notes/7.3.0.md
  • package.json

📝 Walkthrough

Walkthrough

Refactors Crowdin config and scripts, then normalizes MDX anchor syntax in Unraid OS release notes across English and i18n (de, es, fr, zh). No content changes beyond heading anchors; adds/updates select subsection anchors and internal links.

Changes

Docs anchors and Crowdin integration

Layer / File(s) Summary
Crowdin config and scripts
crowdin.yml, package.json
Splits docs file patterns (MDX/MD/JSON/PNG) with MDX v2.4 options; Crowdin npm scripts now pass --branch main.
English release-notes: anchor normalization
docs/unraid-os/release-notes/*
Converts headings to {/* #... */} for Upgrade notes, Known issues, Rolling back, plus select subsections (e.g., macvlan fix, System Drivers, Tailscale).
German i18n: anchor normalization
i18n/de/.../release-notes/*
Applies MDX comment anchors across recurring sections and subsections.
Spanish i18n: anchor normalization
i18n/es/.../release-notes/*
Applies MDX comment anchors across recurring sections and subsections.
French i18n: anchor normalization and link updates
i18n/fr/.../release-notes/*
Normalizes anchors; updates a few internal links (e.g., Tailscale anchor).
Chinese i18n: anchor normalization
i18n/zh/.../release-notes/*
Converts recurring headings to MDX comment anchors; adjusts select subsection anchors.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

  • unraid/docs#475 — Also edits 7.3.0 release notes, overlapping the same file while changing release status content.

Suggested reviewers

  • ljm42

Poem

A rabbit taps keys with a hop and a wink,
Anchors aligned so our docs never sink.
Crowdin sails steady on main’s gentle breeze,
MDX whispers, “Link me, please.”
Across every tongue, the notes now sing—
Hop, hop, hooray for a tidy string! 🐇✨

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/crowdin-mdx-release-note-anchors-main

@elibosley elibosley changed the title [codex] Fix Crowdin MDX heading anchor handling fix: crowdin MDX heading anchor handling May 24, 2026
@elibosley elibosley marked this pull request as ready for review May 24, 2026 03:18
@cloudflare-workers-and-pages
Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Preview URL Updated (UTC)
✅ Deployment successful!
View logs
unraid-docs 30a1983 Commit Preview URL

Branch Preview URL
May 24 2026, 03:19 AM

@coderabbitai coderabbitai Bot requested a review from ljm42 May 24, 2026 03:20
@elibosley elibosley merged commit 56b213d into main May 24, 2026
5 checks passed
@elibosley elibosley deleted the fix/crowdin-mdx-release-note-anchors-main branch May 24, 2026 14:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant